home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 4: GNU Archives / Linux Cubed Series 4 - GNU Archives.iso / gnu / cvs-1.8 / cvs-1 / cvs-1.8.1 / doc / cvs.info-2 < prev    next >
Encoding:
GNU Info File  |  1996-05-06  |  49.2 KB  |  1,371 lines
  1. This is Info file cvs.info, produced by Makeinfo-1.63 from the input
  2. file ./cvs.texinfo.
  3.  
  4.    Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994
  5. Free Software Foundation, Inc.
  6.  
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.  
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided also
  13. that the section entitled "GNU General Public License" is included
  14. exactly as in the original, and provided that the entire resulting
  15. derived work is distributed under the terms of a permission notice
  16. identical to this one.
  17.  
  18.    Permission is granted to copy and distribute translations of this
  19. manual into another language, under the above conditions for modified
  20. versions, except that the section entitled "GNU General Public License"
  21. and this permission notice may be included in translations approved by
  22. the Free Software Foundation instead of in the original English.
  23.  
  24. 
  25. File: cvs.info,  Node: File status,  Next: Updating a file,  Up: Multiple developers
  26.  
  27. File status
  28. ===========
  29.  
  30.    After you have checked out a file out from CVS, it is in one of
  31. these four states:
  32.  
  33. Up-to-date
  34.      The file is identical with the latest revision in the repository.
  35.  
  36. Locally modified
  37.      You have edited the file, and not yet committed your changes.
  38.  
  39. Needing update
  40.      Someone else has committed a newer revision to the repository.
  41.  
  42. Needing merge
  43.      Someone else have committed a newer revision to the repository,
  44.      and you have also made modifications to the file.
  45.  
  46.    You can use the `status' command to find out the status of a given
  47. file.  *Note status::.
  48.  
  49. 
  50. File: cvs.info,  Node: Updating a file,  Next: Conflicts example,  Prev: File status,  Up: Multiple developers
  51.  
  52. Bringing a file up to date
  53. ==========================
  54.  
  55.    When you want to update or merge a file, use the `update' command.
  56. For files that are not up to date this is roughly equivalent to a
  57. `checkout' command: the newest revision of the file is extracted from
  58. the repository and put in your working copy of the module.
  59.  
  60.    Your modifications to a file are never lost when you use `update'.
  61. If no newer revision exists, running `update' has no effect.  If you
  62. have edited the file, and a newer revision is available, CVS will merge
  63. all changes into your working copy.
  64.  
  65.    For instance, imagine that you checked out revision 1.4 and started
  66. editing it.  In the meantime someone else committed revision 1.5, and
  67. shortly after that revision 1.6.  If you run `update' on the file now,
  68. CVS will incorporate all changes between revision 1.4 and 1.6 into your
  69. file.
  70.  
  71.    If any of the changes between 1.4 and 1.6 were made too close to any
  72. of the changes you have made, an "overlap" occurs.  In such cases a
  73. warning is printed, and the resulting file includes both versions of
  74. the lines that overlap, delimited by special markers.  *Note update::,
  75. for a complete description of the `update' command.
  76.  
  77. 
  78. File: cvs.info,  Node: Conflicts example,  Next: Informing others,  Prev: Updating a file,  Up: Multiple developers
  79.  
  80. Conflicts example
  81. =================
  82.  
  83.    Suppose revision 1.4 of `driver.c' contains this:
  84.  
  85.      #include <stdio.h>
  86.      
  87.      void main()
  88.      {
  89.          parse();
  90.          if (nerr == 0)
  91.              gencode();
  92.          else
  93.              fprintf(stderr, "No code generated.\n");
  94.          exit(nerr == 0 ? 0 : 1);
  95.      }
  96.  
  97. Revision 1.6 of `driver.c' contains this:
  98.  
  99.      #include <stdio.h>
  100.      
  101.      int main(int argc,
  102.               char **argv)
  103.      {
  104.          parse();
  105.          if (argc != 1)
  106.          {
  107.              fprintf(stderr, "tc: No args expected.\n");
  108.              exit(1);
  109.          }
  110.          if (nerr == 0)
  111.              gencode();
  112.          else
  113.              fprintf(stderr, "No code generated.\n");
  114.          exit(!!nerr);
  115.      }
  116.  
  117. Your working copy of `driver.c', based on revision 1.4, contains this
  118. before you run `cvs update':
  119.  
  120.      #include <stdlib.h>
  121.      #include <stdio.h>
  122.      
  123.      void main()
  124.      {
  125.          init_scanner();
  126.          parse();
  127.          if (nerr == 0)
  128.              gencode();
  129.          else
  130.              fprintf(stderr, "No code generated.\n");
  131.          exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  132.      }
  133.  
  134. You run `cvs update':
  135.  
  136.      $ cvs update driver.c
  137.      RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
  138.      retrieving revision 1.4
  139.      retrieving revision 1.6
  140.      Merging differences between 1.4 and 1.6 into driver.c
  141.      rcsmerge warning: overlaps during merge
  142.      cvs update: conflicts found in driver.c
  143.      C driver.c
  144.  
  145. CVS tells you that there were some conflicts.  Your original working
  146. file is saved unmodified in `.#driver.c.1.4'.  The new version of
  147. `driver.c' contains this:
  148.  
  149.      #include <stdlib.h>
  150.      #include <stdio.h>
  151.      
  152.      int main(int argc,
  153.               char **argv)
  154.      {
  155.          init_scanner();
  156.          parse();
  157.          if (argc != 1)
  158.          {
  159.              fprintf(stderr, "tc: No args expected.\n");
  160.              exit(1);
  161.          }
  162.          if (nerr == 0)
  163.              gencode();
  164.          else
  165.              fprintf(stderr, "No code generated.\n");
  166.      <<<<<<< driver.c
  167.          exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  168.      =======
  169.          exit(!!nerr);
  170.      >>>>>>> 1.6
  171.      }
  172.  
  173. Note how all non-overlapping modifications are incorporated in your
  174. working copy, and that the overlapping section is clearly marked with
  175. `<<<<<<<', `=======' and `>>>>>>>'.
  176.  
  177.    You resolve the conflict by editing the file, removing the markers
  178. and the erroneous line.  Suppose you end up with this file:
  179.      #include <stdlib.h>
  180.      #include <stdio.h>
  181.      
  182.      int main(int argc,
  183.               char **argv)
  184.      {
  185.          init_scanner();
  186.          parse();
  187.          if (argc != 1)
  188.          {
  189.              fprintf(stderr, "tc: No args expected.\n");
  190.              exit(1);
  191.          }
  192.          if (nerr == 0)
  193.              gencode();
  194.          else
  195.              fprintf(stderr, "No code generated.\n");
  196.          exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  197.      }
  198.  
  199. You can now go ahead and commit this as revision 1.7.
  200.  
  201.      $ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
  202.      Checking in driver.c;
  203.      /usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
  204.      new revision: 1.7; previous revision: 1.6
  205.      done
  206.  
  207.    If you use release 1.04 or later of pcl-cvs (a GNU Emacs front-end
  208. for CVS) you can use an Emacs package called emerge to help you resolve
  209. conflicts.  See the documentation for pcl-cvs.
  210.  
  211. 
  212. File: cvs.info,  Node: Informing others,  Next: Concurrency,  Prev: Conflicts example,  Up: Multiple developers
  213.  
  214. Informing others about commits
  215. ==============================
  216.  
  217.    It is often useful to inform others when you commit a new revision
  218. of a file.  The `-i' option of the `modules' file, or the `loginfo'
  219. file, can be used to automate this process.  *Note modules::.  *Note
  220. loginfo::.  You can use these features of CVS to, for instance,
  221. instruct CVS to mail a message to all developers, or post a message to
  222. a local newsgroup.
  223.  
  224. 
  225. File: cvs.info,  Node: Concurrency,  Next: Watches,  Prev: Informing others,  Up: Multiple developers
  226.  
  227. Several developers simultaneously attempting to run CVS
  228. =======================================================
  229.  
  230.    If several developers try to run CVS at the same time, one may get
  231. the following message:
  232.  
  233.      [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
  234.  
  235.    CVS will try again every 30 seconds, and either continue with the
  236. operation or print the message again, if it still needs to wait.  If a
  237. lock seems to stick around for an undue amount of time, find the person
  238. holding the lock and ask them about the cvs command they are running.
  239. If they aren't running a cvs command, look for and remove files
  240. starting with `#cvs.tfl', `#cvs.rfl', or `#cvs.wfl' from the repository.
  241.  
  242.    Note that these locks are to protect CVS's internal data structures
  243. and have no relationship to the word "lock" in the sense used by RCS-a
  244. way to prevent other developers from working on a particular file.
  245.  
  246.    Any number of people can be reading from a given repository at a
  247. time; only when someone is writing do the locks prevent other people
  248. from reading or writing.
  249.  
  250.    One might hope for the following property
  251.  
  252.      If someone commits some changes in one cvs command,
  253.      then an update by someone else will either get all the
  254.      changes, or none of them.
  255.  
  256.    but CVS does *not* have this property.  For example, given the files
  257.  
  258.      a/one.c
  259.      a/two.c
  260.      b/three.c
  261.      b/four.c
  262.  
  263.    if someone runs
  264.  
  265.      cvs ci a/two.c b/three.c
  266.  
  267.    and someone else runs `cvs update' at the same time, the person
  268. running `update' might get only the change to `b/three.c' and not the
  269. change to `a/two.c'.
  270.  
  271. 
  272. File: cvs.info,  Node: Watches,  Prev: Concurrency,  Up: Multiple developers
  273.  
  274. Mechanisms to track who is editing files
  275. ========================================
  276.  
  277.    For many groups, use of CVS in its default mode is perfectly
  278. satisfactory.  Users may sometimes go to check in a modification only
  279. to find that another modification has intervened, but they deal with it
  280. and proceed with their check in.  Other groups prefer to be able to
  281. know who is editing what files, so that if two people try to edit the
  282. same file they can choose to talk about who is doing what when rather
  283. than be surprised at check in time.  The features in this section allow
  284. such coordination, while retaining the ability of two developers to
  285. edit the same file at the same time.
  286.  
  287.    For maximum benefit developers should use `cvs edit' (not `chmod')
  288. to make files read-write to edit them, and `cvs release' (not `rm') to
  289. discard a working directory which is no longer in use, but CVS is not
  290. able to enforce this behavior.
  291.  
  292. * Menu:
  293.  
  294. * Setting a watch::             Telling CVS to watch certain files
  295. * Getting Notified::            Telling CVS to notify you
  296. * Editing files::               How to edit a file which is being watched
  297. * Watch information::           Information about who is watching and editing
  298. * Watches Compatibility::       Watches interact poorly with CVS 1.6 or earlier
  299.  
  300. 
  301. File: cvs.info,  Node: Setting a watch,  Next: Getting Notified,  Up: Watches
  302.  
  303. Telling CVS to watch certain files
  304. ----------------------------------
  305.  
  306.    To enable the watch features, you first specify that certain files
  307. are to be watched.
  308.  
  309.  - Command: cvs watch on [`-l'] FILES ...
  310.      Specify that developers should run `cvs edit' before editing
  311.      FILES.  CVS will create working copies of FILES read-only, to
  312.      remind developers to run the `cvs edit' command before working on
  313.      them.
  314.  
  315.      If FILES includes the name of a directory, CVS arranges to watch
  316.      all files added to the corresponding repository directory, and
  317.      sets a default for files added in the future; this allows the user
  318.      to set notification policies on a per-directory basis.  The
  319.      contents of the directory are processed recursively, unless the
  320.      `-l' option is given.
  321.  
  322.      If FILES is omitted, it defaults to the current directory.
  323.  
  324.  
  325.  - Command: cvs watch off [`-l'] FILES ...
  326.      Do not provide notification about work on FILES.  CVS will create
  327.      working copies of FILES read-write.
  328.  
  329.      The FILES and `-l' arguments are processed as for `cvs watch on'.
  330.  
  331.  
  332. 
  333. File: cvs.info,  Node: Getting Notified,  Next: Editing files,  Prev: Setting a watch,  Up: Watches
  334.  
  335. Telling CVS to notify you
  336. -------------------------
  337.  
  338.    You can tell CVS that you want to receive notifications about
  339. various actions taken on a file.  You can do this without using `cvs
  340. watch on' for the file, but generally you will want to use `cvs watch
  341. on', so that developers use the `cvs edit' command.
  342.  
  343.  - Command: cvs watch add [`-a' ACTION] [`-l'] FILES ...
  344.      Add the current user to the list of people to receive notification
  345.      of work done on FILES.
  346.  
  347.      The `-a' option specifies what kinds of events CVS should notify
  348.      the user about.  ACTION is one of the following:
  349.  
  350.     `edit'
  351.           Another user has applied the `cvs edit' command (described
  352.           below) to a file.
  353.  
  354.     `unedit'
  355.           Another user has applied the `cvs unedit' command (described
  356.           below) or the `cvs release' command to a file, or has deleted
  357.           the file and allowed `cvs update' to recreate it.
  358.  
  359.     `commit'
  360.           Another user has committed changes to a file.
  361.  
  362.     `all'
  363.           All of the above.
  364.  
  365.     `none'
  366.           None of the above.  (This is useful with `cvs edit',
  367.           described below.)
  368.  
  369.      The `-a' option may appear more than once, or not at all.  If
  370.      omitted, the action defaults to `all'.
  371.  
  372.      The FILES and `-l' option are processed as for the `cvs watch'
  373.      commands.
  374.  
  375.  
  376.  - Command: cvs watch remove [`-a' ACTION] [`-l'] FILES ...
  377.      Remove a notification request established using `cvs watch add';
  378.      the arguments are the same.  If the `-a' option is present, only
  379.      watches for the specified actions are removed.
  380.  
  381.  
  382.    When the conditions exist for notification, CVS calls the `notify'
  383. administrative file, passing it the user to receive the notification
  384. and the user who is taking the action which results in notification.
  385. Normally `notify' will just send an email message.
  386.  
  387.    Note that if you set this up in the straightforward way, users
  388. receive notifications on the server machine.  One could of course write
  389. a `notify' script which directed notifications elsewhere, but to make
  390. this easy, CVS allows you to associate a notification address for each
  391. user.  To do so create a file `users' in `CVSROOT' with a line for each
  392. user in the format USER:VALUE.  Then instead of passing the name of the
  393. user to be notified to `notify', CVS will pass the VALUE (normally an
  394. email address on some other machine).
  395.  
  396. 
  397. File: cvs.info,  Node: Editing files,  Next: Watch information,  Prev: Getting Notified,  Up: Watches
  398.  
  399. How to edit a file which is being watched
  400. -----------------------------------------
  401.  
  402.    Since a file which is being watched is checked out read-only, you
  403. cannot simply edit it.  To make it read-write, and inform others that
  404. you are planning to edit it, use the `cvs edit' command.
  405.  
  406.  - Command: cvs edit [OPTIONS] FILES ...
  407.      Prepare to edit the working files FILES.  CVS makes the FILES
  408.      read-write, and notifies users who have requested `edit'
  409.      notification for any of FILES.
  410.  
  411.      The `cvs edit' command accepts the same OPTIONS as the `cvs watch
  412.      add' command, and establishes a temporary watch for the user on
  413.      FILES; CVS will remove the watch when FILES are `unedit'ed or
  414.      `commit'ted.  If the user does not wish to receive notifications,
  415.      she should specify `-a none'.
  416.  
  417.      The FILES and `-l' option are processed as for the `cvs watch'
  418.      commands.
  419.  
  420.  
  421.    Normally when you are done with a set of changes, you use the `cvs
  422. commit' command, which checks in your changes and returns the watched
  423. files to their usual read-only state.  But if you instead decide to
  424. abandon your changes, or not to make any changes, you can use the `cvs
  425. unedit' command.
  426.  
  427.  - Command: cvs unedit [`-l'] FILES ...
  428.      Abandon work on the working files FILES, and revert them to the
  429.      repository versions on which they are based.  CVS makes those
  430.      FILES read-only for which users have requested notification using
  431.      `cvs watch on'.  CVS notifies users who have requested `unedit'
  432.      notification for any of FILES.
  433.  
  434.      The FILES and `-l' option are processed as for the `cvs watch'
  435.      commands.
  436.  
  437.  
  438.    When using client/server CVS, you can use the `cvs edit' and `cvs
  439. unedit' commands even if CVS is unable to succesfully communicate with
  440. the server; the notifications will be sent upon the next successful CVS
  441. command.
  442.  
  443. 
  444. File: cvs.info,  Node: Watch information,  Next: Watches Compatibility,  Prev: Editing files,  Up: Watches
  445.  
  446. Information about who is watching and editing
  447. ---------------------------------------------
  448.  
  449.  - Command: cvs watchers [`-l'] FILES ...
  450.      List the users currently watching changes to FILES.  The report
  451.      includes the files being watched, and the mail address of each
  452.      watcher.
  453.  
  454.      The FILES and `-l' arguments are processed as for the `cvs watch'
  455.      commands.
  456.  
  457.  
  458.  - Command: cvs editors [`-l'] FILES ...
  459.      List the users currently working on FILES.  The report includes
  460.      the mail address of each user, the time when the user began
  461.      working with the file, and the host and path of the working
  462.      directory containing the file.
  463.  
  464.      The FILES and `-l' arguments are processed as for the `cvs watch'
  465.      commands.
  466.  
  467.  
  468. 
  469. File: cvs.info,  Node: Watches Compatibility,  Prev: Watch information,  Up: Watches
  470.  
  471. Using watches with old versions of CVS
  472. --------------------------------------
  473.  
  474.    If you use the watch features on a repository, it creates `CVS'
  475. directories in the repository and stores the information about watches
  476. in that directory.  If you attempt to use CVS 1.6 or earlier with the
  477. repository, you get an error message such as
  478.  
  479.      cvs update: cannot open CVS/Entries for reading: No such file or directory
  480.  
  481.    and your operation will likely be aborted.  To use the watch
  482. features, you must upgrade all copies of CVS which use that repository
  483. in local or server mode.  If you cannot upgrade, use the `watch off' and
  484. `watch remove' commands to remove all watches, and that will restore
  485. the repository to a state which CVS 1.6 can cope with.
  486.  
  487. 
  488. File: cvs.info,  Node: Branches,  Next: Merging,  Prev: Multiple developers,  Up: Top
  489.  
  490. Branches
  491. ********
  492.  
  493.    So far, all revisions shown in this manual have been on the "main
  494. trunk" of the revision tree, i.e., all revision numbers have been of
  495. the form X.Y.  One useful feature, especially when maintaining several
  496. releases of a software product at once, is the ability to make branches
  497. on the revision tree.  "Tags", symbolic names for revisions, will also
  498. be introduced in this chapter.
  499.  
  500. * Menu:
  501.  
  502. * Tags::                        Tags-Symbolic revisions
  503. * Branches motivation::         What branches are good for
  504. * Creating a branch::           Creating a branch
  505. * Sticky tags::                 Sticky tags
  506.  
  507. 
  508. File: cvs.info,  Node: Tags,  Next: Branches motivation,  Up: Branches
  509.  
  510. Tags-Symbolic revisions
  511. =======================
  512.  
  513.    The revision numbers live a life of their own.  They need not have
  514. anything at all to do with the release numbers of your software
  515. product.  Depending on how you use CVS the revision numbers might
  516. change several times between two releases.  As an example, some of the
  517. source files that make up RCS 5.6 have the following revision numbers:
  518.  
  519.      ci.c            5.21
  520.      co.c            5.9
  521.      ident.c         5.3
  522.      rcs.c           5.12
  523.      rcsbase.h       5.11
  524.      rcsdiff.c       5.10
  525.      rcsedit.c       5.11
  526.      rcsfcmp.c       5.9
  527.      rcsgen.c        5.10
  528.      rcslex.c        5.11
  529.      rcsmap.c        5.2
  530.      rcsutil.c       5.10
  531.  
  532.    You can use the `tag' command to give a symbolic name to a certain
  533. revision of a file.  You can use the `-v' flag to the `status' command
  534. to see all tags that a file has, and which revision numbers they
  535. represent.  Tag names can contain uppercase and lowercase letters,
  536. digits, `-', and `_'.  The two tag names `BASE' and `HEAD' are reserved
  537. for use by CVS.  It is expected that future names which are special to
  538. CVS will contain characters such as `%' or `=', rather than being named
  539. analogously to `BASE' and `HEAD', to avoid conflicts with actual tag
  540. names.
  541.  
  542.    The following example shows how you can add a tag to a file.  The
  543. commands must be issued inside your working copy of the module.  That
  544. is, you should issue the command in the directory where `backend.c'
  545. resides.
  546.  
  547.      $ cvs tag release-0-4 backend.c
  548.      T backend.c
  549.      $ cvs status -v backend.c
  550.      ===================================================================
  551.      File: backend.c         Status: Up-to-date
  552.      
  553.          Version:            1.4     Tue Dec  1 14:39:01 1992
  554.          RCS Version:        1.4     /usr/local/cvsroot/yoyodyne/tc/backend.c,v
  555.          Sticky Tag:         (none)
  556.          Sticky Date:        (none)
  557.          Sticky Options:     (none)
  558.      
  559.          Existing Tags:
  560.              release-0-4                     (revision: 1.4)
  561.  
  562.    There is seldom reason to tag a file in isolation.  A more common
  563. use is to tag all the files that constitute a module with the same tag
  564. at strategic points in the development life-cycle, such as when a
  565. release is made.
  566.  
  567.      $ cvs tag release-1-0 .
  568.      cvs tag: Tagging .
  569.      T Makefile
  570.      T backend.c
  571.      T driver.c
  572.      T frontend.c
  573.      T parser.c
  574.  
  575.    (When you give CVS a directory as argument, it generally applies the
  576. operation to all the files in that directory, and (recursively), to any
  577. subdirectories that it may contain.  *Note Recursive behavior::.)
  578.  
  579.    The `checkout' command has a flag, `-r', that lets you check out a
  580. certain revision of a module.  This flag makes it easy to retrieve the
  581. sources that make up release 1.0 of the module `tc' at any time in the
  582. future:
  583.  
  584.      $ cvs checkout -r release-1-0 tc
  585.  
  586. This is useful, for instance, if someone claims that there is a bug in
  587. that release, but you cannot find the bug in the current working copy.
  588.  
  589.    You can also check out a module as it was at any given date.  *Note
  590. checkout options::.
  591.  
  592.    When you tag more than one file with the same tag you can think
  593. about the tag as "a curve drawn through a matrix of filename vs.
  594. revision number."  Say we have 5 files with the following revisions:
  595.  
  596.              file1   file2   file3   file4   file5
  597.      
  598.              1.1     1.1     1.1     1.1  /--1.1*      <-*-  TAG
  599.              1.2*-   1.2     1.2    -1.2*-
  600.              1.3  \- 1.3*-   1.3   / 1.3
  601.              1.4          \  1.4  /  1.4
  602.                            \-1.5*-   1.5
  603.                              1.6
  604.  
  605.    At some time in the past, the `*' versions were tagged.  You can
  606. think of the tag as a handle attached to the curve drawn through the
  607. tagged revisions.  When you pull on the handle, you get all the tagged
  608. revisions.  Another way to look at it is that you "sight" through a set
  609. of revisions that is "flat" along the tagged revisions, like this:
  610.  
  611.              file1   file2   file3   file4   file5
  612.      
  613.                              1.1
  614.                              1.2
  615.                      1.1     1.3                       _
  616.              1.1     1.2     1.4     1.1              /
  617.              1.2*----1.3*----1.5*----1.2*----1.1     (--- <--- Look here
  618.              1.3             1.6     1.3              \_
  619.              1.4                     1.4
  620.                                      1.5
  621.  
  622. 
  623. File: cvs.info,  Node: Branches motivation,  Next: Creating a branch,  Prev: Tags,  Up: Branches
  624.  
  625. What branches are good for
  626. ==========================
  627.  
  628.    Suppose that release 1.0 of tc has been made.  You are continuing to
  629. develop tc, planning to create release 1.1 in a couple of months.
  630. After a while your customers start to complain about a fatal bug.  You
  631. check out release 1.0 (*note Tags::.) and find the bug (which turns out
  632. to have a trivial fix).  However, the current revision of the sources
  633. are in a state of flux and are not expected to be stable for at least
  634. another month.  There is no way to make a bugfix release based on the
  635. newest sources.
  636.  
  637.    The thing to do in a situation like this is to create a "branch" on
  638. the revision trees for all the files that make up release 1.0 of tc.
  639. You can then make modifications to the branch without disturbing the
  640. main trunk.  When the modifications are finished you can select to
  641. either incorporate them on the main trunk, or leave them on the branch.
  642.  
  643. 
  644. File: cvs.info,  Node: Creating a branch,  Next: Sticky tags,  Prev: Branches motivation,  Up: Branches
  645.  
  646. Creating a branch
  647. =================
  648.  
  649.    The `rtag' command can be used to create a branch.  The `rtag'
  650. command is much like `tag', but it does not require that you have a
  651. working copy of the module.  *Note rtag::.  (You can also use the `tag'
  652. command; *note tag::.).
  653.  
  654.      $ cvs rtag -b -r release-1-0 release-1-0-patches tc
  655.  
  656.    The `-b' flag makes `rtag' create a branch (rather than just a
  657. symbolic revision name).  `-r release-1-0' says that this branch should
  658. be rooted at the node (in the revision tree) that corresponds to the tag
  659. `release-1-0'.  Note that the numeric revision number that matches
  660. `release-1-0' will probably be different from file to file.  The name
  661. of the new branch is `release-1-0-patches', and the module affected is
  662. `tc'.
  663.  
  664.    To fix the problem in release 1.0, you need a working copy of the
  665. branch you just created.
  666.  
  667.      $ cvs checkout -r release-1-0-patches tc
  668.      $ cvs status -v driver.c backend.c
  669.      ===================================================================
  670.      File: driver.c          Status: Up-to-date
  671.      
  672.          Version:            1.7     Sat Dec  5 18:25:54 1992
  673.          RCS Version:        1.7     /usr/local/cvsroot/yoyodyne/tc/driver.c,v
  674.          Sticky Tag:         release-1-0-patches (branch: 1.7.2)
  675.          Sticky Date:        (none)
  676.          Sticky Options:     (none)
  677.      
  678.          Existing Tags:
  679.              release-1-0-patches             (branch: 1.7.2)
  680.              release-1-0                     (revision: 1.7)
  681.      
  682.      ===================================================================
  683.      File: backend.c         Status: Up-to-date
  684.      
  685.          Version:            1.4     Tue Dec  1 14:39:01 1992
  686.          RCS Version:        1.4     /usr/local/cvsroot/yoyodyne/tc/backend.c,v
  687.          Sticky Tag:         release-1-0-patches (branch: 1.4.2)
  688.          Sticky Date:        (none)
  689.          Sticky Options:     (none)
  690.      
  691.          Existing Tags:
  692.              release-1-0-patches             (branch: 1.4.2)
  693.              release-1-0                     (revision: 1.4)
  694.              release-0-4                     (revision: 1.4)
  695.  
  696.    As the output from the `status' command shows the branch number is
  697. created by adding a digit at the tail of the revision number it is
  698. based on.  (If `release-1-0' corresponds to revision 1.4, the branch's
  699. revision number will be 1.4.2.  For obscure reasons CVS always gives
  700. branches even numbers, starting at 2.  *Note Revision numbers::).
  701.  
  702. 
  703. File: cvs.info,  Node: Sticky tags,  Prev: Creating a branch,  Up: Branches
  704.  
  705. Sticky tags
  706. ===========
  707.  
  708.    The `-r release-1-0-patches' flag that was given to `checkout' in
  709. the previous example is "sticky", that is, it will apply to subsequent
  710. commands in this directory.  If you commit any modifications, they are
  711. committed on the branch.  You can later merge the modifications into
  712. the main trunk.  *Note Merging::.
  713.  
  714.    You can use the `status' command to see what sticky tags or dates
  715. are set:
  716.  
  717.      $ vi driver.c   # Fix the bugs
  718.      $ cvs commit -m "Fixed initialization bug" driver.c
  719.      Checking in driver.c;
  720.      /usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
  721.      new revision: 1.7.2.1; previous revision: 1.7
  722.      done
  723.      $ cvs status -v driver.c
  724.      ===================================================================
  725.      File: driver.c          Status: Up-to-date
  726.      
  727.          Version:            1.7.2.1 Sat Dec  5 19:35:03 1992
  728.          RCS Version:        1.7.2.1 /usr/local/cvsroot/yoyodyne/tc/driver.c,v
  729.          Sticky Tag:         release-1-0-patches (branch: 1.7.2)
  730.          Sticky Date:        (none)
  731.          Sticky Options:     (none)
  732.      
  733.          Existing Tags:
  734.              release-1-0-patches             (branch: 1.7.2)
  735.              release-1-0                     (revision: 1.7)
  736.  
  737.    The sticky tags will remain on your working files until you delete
  738. them with `cvs update -A'.  The `-A' option retrieves the version of
  739. the file from the head of the trunk, and forgets any sticky tags,
  740. dates, or options.
  741.  
  742.    Sticky tags are not just for branches.  If you check out a certain
  743. revision (such as 1.4) it will also become sticky.  Subsequent `cvs
  744. update' will not retrieve the latest revision until you reset the tag
  745. with `cvs update -A'.  Likewise, use of the `-D' option to `update' or
  746. `checkout' sets a "sticky date", which, similarly, causes that date to
  747. be used for future retrievals.
  748.  
  749.    Many times you will want to retrieve an old version of a file
  750. without setting a sticky tag.  The way to do that is with the `-p'
  751. option to `checkout' or `update', which sends the contents of the file
  752. to standard output.  For example, suppose you have a file named `file1'
  753. which existed as revision 1.1, and you then removed it (thus adding a
  754. dead revision 1.2).  Now suppose you want to add it again, with the same
  755. contents it had previously.  Here is how to do it:
  756.  
  757.      $ cvs update -p -r 1.1 file1 >file1
  758.      ===================================================================
  759.      Checking out file1
  760.      RCS:  /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
  761.      VERS: 1.1
  762.      ***************
  763.      $ cvs add file1
  764.      cvs add: version 1.2 of `file1' will be resurrected
  765.      cvs add: use 'cvs commit' to add this file permanently
  766.      $ cvs commit -m test
  767.      Checking in file1;
  768.      /tmp/cvs-sanity/cvsroot/first-dir/file1,v  <--  file1
  769.      new revision: 1.3; previous revision: 1.2
  770.      done
  771.      $
  772.  
  773. 
  774. File: cvs.info,  Node: Merging,  Next: Recursive behavior,  Prev: Branches,  Up: Top
  775.  
  776. Merging
  777. *******
  778.  
  779.    You can include the changes made between any two revisions into your
  780. working copy, by "merging".  You can then commit that revision, and
  781. thus effectively copy the changes onto another branch.
  782.  
  783. * Menu:
  784.  
  785. * Merging a branch::            Merging an entire branch
  786. * Merging more than once::      Merging from a branch several times
  787. * Merging two revisions::       Merging differences between two revisions
  788.  
  789. 
  790. File: cvs.info,  Node: Merging a branch,  Next: Merging more than once,  Up: Merging
  791.  
  792. Merging an entire branch
  793. ========================
  794.  
  795.    You can merge changes made on a branch into your working copy by
  796. giving the `-j BRANCH' flag to the `update' command.  With one `-j
  797. BRANCH' option it merges the changes made between the point where the
  798. branch forked and newest revision on that branch (into your working
  799. copy).
  800.  
  801.    The `-j' stands for "join".
  802.  
  803.    Consider this revision tree:
  804.  
  805.      +-----+    +-----+    +-----+    +-----+
  806.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !      <- The main trunk
  807.      +-----+    +-----+    +-----+    +-----+
  808.                      !
  809.                      !
  810.                      !   +---------+    +---------+
  811.      Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
  812.                          +---------+    +---------+
  813.  
  814. The branch 1.2.2 has been given the tag (symbolic name) `R1fix'.  The
  815. following example assumes that the module `mod' contains only one file,
  816. `m.c'.
  817.  
  818.      $ cvs checkout mod               # Retrieve the latest revision, 1.4
  819.      
  820.      $ cvs update -j R1fix m.c        # Merge all changes made on the branch,
  821.                                       # i.e. the changes between revision 1.2
  822.                                       # and 1.2.2.2, into your working copy
  823.                                       # of the file.
  824.      
  825.      $ cvs commit -m "Included R1fix" # Create revision 1.5.
  826.  
  827.    A conflict can result from a merge operation.  If that happens, you
  828. should resolve it before committing the new revision.  *Note Conflicts
  829. example::.
  830.  
  831.    The `checkout' command also supports the `-j BRANCH' flag.  The same
  832. effect as above could be achieved with this:
  833.  
  834.      $ cvs checkout -j R1fix mod
  835.      $ cvs commit -m "Included R1fix"
  836.  
  837. 
  838. File: cvs.info,  Node: Merging more than once,  Next: Merging two revisions,  Prev: Merging a branch,  Up: Merging
  839.  
  840. Merging from a branch several times
  841. ===================================
  842.  
  843.    Continuing our example, the revision tree now looks like this:
  844.  
  845.      +-----+    +-----+    +-----+    +-----+    +-----+
  846.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
  847.      +-----+    +-----+    +-----+    +-----+    +-----+
  848.                      !                           *
  849.                      !                          *
  850.                      !   +---------+    +---------+
  851.      Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
  852.                          +---------+    +---------+
  853.  
  854.    where the starred line represents the merge from the `R1fix' branch
  855. to the main trunk, as just discussed.
  856.  
  857.    Now suppose that development continues on the `R1fix' branch:
  858.  
  859.      +-----+    +-----+    +-----+    +-----+    +-----+
  860.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
  861.      +-----+    +-----+    +-----+    +-----+    +-----+
  862.                      !                           *
  863.                      !                          *
  864.                      !   +---------+    +---------+    +---------+
  865.      Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
  866.                          +---------+    +---------+    +---------+
  867.  
  868.    and then you want to merge those new changes onto the main trunk.
  869. If you just use the `cvs update -j R1fix m.c' command again, CVS will
  870. attempt to merge again the changes which you have already merged, which
  871. can have undesirable side effects.
  872.  
  873.    So instead you need to specify that you only want to merge the
  874. changes on the branch which have not yet been merged into the trunk.
  875. To do that you specify two `-j' options, and CVS merges the changes from
  876. the first revision to the second revision.  For example, in this case
  877. the simplest way would be
  878.  
  879.      cvs update -j 1.2.2.2 -j R1fix m.c    # Merge changes from 1.2.2.2 to the
  880.                                            # head of the R1fix branch
  881.  
  882.    The problem with this is that you need to specify the 1.2.2.2
  883. revision manually.  A slightly better approach might be to use the date
  884. the last merge was done:
  885.  
  886.      cvs update -j R1fix:yesterday -j R1fix m.c
  887.  
  888.    Better yet, tag the R1fix branch after every merge into the trunk,
  889. and then use that tag for subsequent merges:
  890.  
  891.      cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
  892.  
  893. 
  894. File: cvs.info,  Node: Merging two revisions,  Prev: Merging more than once,  Up: Merging
  895.  
  896. Merging differences between any two revisions
  897. =============================================
  898.  
  899.    With two `-j REVISION' flags, the `update' (and `checkout') command
  900. can merge the differences between any two revisions into your working
  901. file.
  902.  
  903.      $ cvs update -j 1.5 -j 1.3 backend.c
  904.  
  905. will *remove* all changes made between revision 1.3 and 1.5.  Note the
  906. order of the revisions!
  907.  
  908.    If you try to use this option when operating on multiple files,
  909. remember that the numeric revisions will probably be very different
  910. between the various files that make up a module.  You almost always use
  911. symbolic tags rather than revision numbers when operating on multiple
  912. files.
  913.  
  914. 
  915. File: cvs.info,  Node: Recursive behavior,  Next: Adding files,  Prev: Merging,  Up: Top
  916.  
  917. Recursive behavior
  918. ******************
  919.  
  920.    Almost all of the subcommands of CVS work recursively when you
  921. specify a directory as an argument.  For instance, consider this
  922. directory structure:
  923.  
  924.            `$HOME'
  925.              |
  926.              +--tc
  927.              |   |
  928.                  +--CVS
  929.                  |      (internal CVS files)
  930.                  +--Makefile
  931.                  +--backend.c
  932.                  +--driver.c
  933.                  +--frontend.c
  934.                  +--parser.c
  935.                  +--man
  936.                  |    |
  937.                  |    +--CVS
  938.                  |    |  (internal CVS files)
  939.                  |    +--tc.1
  940.                  |
  941.                  +--testing
  942.                       |
  943.                       +--CVS
  944.                       |  (internal CVS files)
  945.                       +--testpgm.t
  946.                       +--test2.t
  947.  
  948. If `tc' is the current working directory, the following is true:
  949.  
  950.    * `cvs update testing' is equivalent to `cvs update
  951.      testing/testpgm.t testing/test2.t'
  952.  
  953.    * `cvs update testing man' updates all files in the subdirectories
  954.  
  955.    * `cvs update .' or just `cvs update' updates all files in the `tc'
  956.      module
  957.  
  958.    If no arguments are given to `update' it will update all files in
  959. the current working directory and all its subdirectories.  In other
  960. words, `.' is a default argument to `update'.  This is also true for
  961. most of the CVS subcommands, not only the `update' command.
  962.  
  963.    The recursive behavior of the CVS subcommands can be turned off with
  964. the `-l' option.
  965.  
  966.      $ cvs update -l         # Don't update files in subdirectories
  967.  
  968. 
  969. File: cvs.info,  Node: Adding files,  Next: Removing files,  Prev: Recursive behavior,  Up: Top
  970.  
  971. Adding files to a module
  972. ************************
  973.  
  974.    To add a new file to a module, follow these steps.
  975.  
  976.    * You must have a working copy of the module.  *Note Getting the
  977.      source::.
  978.  
  979.    * Create the new file inside your working copy of the module.
  980.  
  981.    * Use `cvs add FILENAME' to tell CVS that you want to version
  982.      control the file.
  983.  
  984.    * Use `cvs commit FILENAME' to actually check in the file into the
  985.      repository.  Other developers cannot see the file until you
  986.      perform this step.
  987.  
  988.    * If the file contains binary data it might be necessary to change
  989.      the default keyword substitution.  *Note Keyword substitution::.
  990.      *Note admin examples::.
  991.  
  992.    You can also use the `add' command to add a new directory inside a
  993. module.
  994.  
  995.    Unlike most other commands, the `add' command is not recursive.  You
  996. cannot even type `cvs add foo/bar'!  Instead, you have to
  997.  
  998.      $ cd foo
  999.      $ cvs add bar
  1000.  
  1001.    *Note add::, for a more complete description of the `add' command.
  1002.  
  1003. 
  1004. File: cvs.info,  Node: Removing files,  Next: Tracking sources,  Prev: Adding files,  Up: Top
  1005.  
  1006. Removing files from a module
  1007. ****************************
  1008.  
  1009.    Modules change.  New files are added, and old files disappear.
  1010. Still, you want to be able to retrieve an exact copy of old releases of
  1011. the module.
  1012.  
  1013.    Here is what you can do to remove a file from a module, but remain
  1014. able to retrieve old revisions:
  1015.  
  1016.    * Make sure that you have not made any uncommitted modifications to
  1017.      the file.  *Note Viewing differences::, for one way to do that.
  1018.      You can also use the `status' or `update' command.  If you remove
  1019.      the file without committing your changes, you will of course not
  1020.      be able to retrieve the file as it was immediately before you
  1021.      deleted it.
  1022.  
  1023.    * Remove the file from your working copy of the module.  You can for
  1024.      instance use `rm'.
  1025.  
  1026.    * Use `cvs remove FILENAME' to tell CVS that you really want to
  1027.      delete the file.
  1028.  
  1029.    * Use `cvs commit FILENAME' to actually perform the removal of the
  1030.      file from the repository.
  1031.  
  1032.    When you commit the removal of the file, CVS records the fact that
  1033. the file no longer exists.  It is possible for a file to exist on only
  1034. some branches and not on others, or to re-add another file with the same
  1035. name later.  CVS will correctly create or not create the file, based on
  1036. the `-r' and `-D' options specified to `checkout' or `update'.
  1037.  
  1038.  - Command: cvs remove [`-lR'] FILES ...
  1039.      Schedule file(s) to be removed from the repository (files which
  1040.      have not already been removed from the working directory are not
  1041.      processed).  This command does not actually remove the file from
  1042.      the repository until you commit the removal.  The `-R' option (the
  1043.      default) specifies that it will recurse into subdirectories; `-l'
  1044.      specifies that it will not.
  1045.  
  1046.    Here is an example of removing several files:
  1047.  
  1048.      $ cd test
  1049.      $ rm ?.c
  1050.      $ cvs remove
  1051.      cvs remove: Removing .
  1052.      cvs remove: scheduling a.c for removal
  1053.      cvs remove: scheduling b.c for removal
  1054.      cvs remove: use 'cvs commit' to remove these files permanently
  1055.      $ cvs ci -m "Removed unneeded files"
  1056.      cvs commit: Examining .
  1057.      cvs commit: Committing .
  1058.  
  1059.    If you change your mind you can easily resurrect the file before you
  1060. commit it, using the `add' command.
  1061.  
  1062.      $ ls
  1063.      CVS   ja.h  oj.c
  1064.      $ rm oj.c
  1065.      $ cvs remove oj.c
  1066.      cvs remove: scheduling oj.c for removal
  1067.      cvs remove: use 'cvs commit' to remove this file permanently
  1068.      $ cvs add oj.c
  1069.      U oj.c
  1070.      cvs add: oj.c, version 1.1.1.1, resurrected
  1071.  
  1072.    If you realize your mistake before you run the `remove' command you
  1073. can use `update' to resurrect the file:
  1074.  
  1075.      $ rm oj.c
  1076.      $ cvs update oj.c
  1077.      cvs update: warning: oj.c was lost
  1078.      U oj.c
  1079.  
  1080. 
  1081. File: cvs.info,  Node: Tracking sources,  Next: Moving files,  Prev: Removing files,  Up: Top
  1082.  
  1083. Tracking third-party sources
  1084. ****************************
  1085.  
  1086.    If you modify a program to better fit your site, you probably want
  1087. to include your modifications when the next release of the program
  1088. arrives.  CVS can help you with this task.
  1089.  
  1090.    In the terminology used in CVS, the supplier of the program is
  1091. called a "vendor".  The unmodified distribution from the vendor is
  1092. checked in on its own branch, the "vendor branch".  CVS reserves branch
  1093. 1.1.1 for this use.
  1094.  
  1095.    When you modify the source and commit it, your revision will end up
  1096. on the main trunk.  When a new release is made by the vendor, you
  1097. commit it on the vendor branch and copy the modifications onto the main
  1098. trunk.
  1099.  
  1100.    Use the `import' command to create and update the vendor branch.
  1101. After a successful `import' the vendor branch is made the `head'
  1102. revision, so anyone that checks out a copy of the file gets that
  1103. revision.  When a local modification is committed it is placed on the
  1104. main trunk, and made the `head' revision.
  1105.  
  1106. * Menu:
  1107.  
  1108. * First import::                Importing a module for the first time
  1109. * Update imports::              Updating a module with the import command
  1110.  
  1111. 
  1112. File: cvs.info,  Node: First import,  Next: Update imports,  Up: Tracking sources
  1113.  
  1114. Importing a module for the first time
  1115. =====================================
  1116.  
  1117.    Use the `import' command to check in the sources for the first time.
  1118. When you use the `import' command to track third-party sources, the
  1119. "vendor tag" and "release tags" are useful.  The "vendor tag" is a
  1120. symbolic name for the branch (which is always 1.1.1, unless you use the
  1121. `-b BRANCH' flag--*Note import options::).  The "release tags" are
  1122. symbolic names for a particular release, such as `FSF_0_04'.
  1123.  
  1124.    Suppose you use `wdiff' (a variant of `diff' that ignores changes
  1125. that only involve whitespace), and are going to make private
  1126. modifications that you want to be able to use even when new releases
  1127. are made in the future.  You start by importing the source to your
  1128. repository:
  1129.  
  1130.      $ tar xfz wdiff-0.04.tar.gz
  1131.      $ cd wdiff-0.04
  1132.      $ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
  1133.  
  1134.    The vendor tag is named `FSF_DIST' in the above example, and the
  1135. only release tag assigned is `WDIFF_0_04'.
  1136.  
  1137. 
  1138. File: cvs.info,  Node: Update imports,  Prev: First import,  Up: Tracking sources
  1139.  
  1140. Updating a module with the import command
  1141. =========================================
  1142.  
  1143.    When a new release of the source arrives, you import it into the
  1144. repository with the same `import' command that you used to set up the
  1145. repository in the first place.  The only difference is that you specify
  1146. a different release tag this time.
  1147.  
  1148.      $ tar xfz wdiff-0.05.tar.gz
  1149.      $ cd wdiff-0.05
  1150.      $ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
  1151.  
  1152.    For files that have not been modified locally, the newly created
  1153. revision becomes the head revision.  If you have made local changes,
  1154. `import' will warn you that you must merge the changes into the main
  1155. trunk, and tell you to use `checkout -j' to do so.
  1156.  
  1157.      $ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
  1158.  
  1159. The above command will check out the latest revision of `wdiff',
  1160. merging the changes made on the vendor branch `FSF_DIST' since
  1161. yesterday into the working copy.  If any conflicts arise during the
  1162. merge they should be resolved in the normal way (*note Conflicts
  1163. example::.).  Then, the modified files may be committed.
  1164.  
  1165.    Using a date, as suggested above, assumes that you do not import
  1166. more than one release of a product per day. If you do, you can always
  1167. use something like this instead:
  1168.  
  1169.      $ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
  1170.  
  1171. In this case, the two above commands are equivalent.
  1172.  
  1173. 
  1174. File: cvs.info,  Node: Moving files,  Next: Moving directories,  Prev: Tracking sources,  Up: Top
  1175.  
  1176. Moving and renaming files
  1177. *************************
  1178.  
  1179.    Moving files to a different directory or renaming them is not
  1180. difficult, but some of the ways in which this works may be non-obvious.
  1181. (Moving or renaming a directory is even harder.  *Note Moving
  1182. directories::).
  1183.  
  1184.    The examples below assume that the file OLD is renamed to NEW.
  1185.  
  1186. * Menu:
  1187.  
  1188. * Outside::                     The normal way to Rename
  1189. * Inside::                      A tricky, alternative way
  1190. * Rename by copying::           Another tricky, alternative way
  1191.  
  1192. 
  1193. File: cvs.info,  Node: Outside,  Next: Inside,  Up: Moving files
  1194.  
  1195. The Normal way to Rename
  1196. ========================
  1197.  
  1198.    The normal way to move a file is to copy OLD to NEW, and then issue
  1199. the normal CVS commands to remove OLD from the repository, and add NEW
  1200. to it.  (Both OLD and NEW could contain relative paths, for example
  1201. `foo/bar.c').
  1202.  
  1203.      $ mv OLD NEW
  1204.      $ cvs remove OLD
  1205.      $ cvs add NEW
  1206.      $ cvs commit -m "Renamed OLD to NEW" OLD NEW
  1207.  
  1208.    This is the simplest way to move a file, it is not error-prone, and
  1209. it preserves the history of what was done.  Note that to access the
  1210. history of the file you must specify the old or the new name, depending
  1211. on what portion of the history you are accessing.  For example, `cvs
  1212. log OLD' will give the log up until the time of the rename.
  1213.  
  1214.    When NEW is committed its revision numbers will start at 1.0 again,
  1215. so if that bothers you, use the `-r rev' option to commit (*note commit
  1216. options::.)
  1217.  
  1218. 
  1219. File: cvs.info,  Node: Inside,  Next: Rename by copying,  Prev: Outside,  Up: Moving files
  1220.  
  1221. Moving the history file
  1222. =======================
  1223.  
  1224.    This method is more dangerous, since it involves moving files inside
  1225. the repository.  Read this entire section before trying it out!
  1226.  
  1227.      $ cd $CVSROOT/MODULE
  1228.      $ mv OLD,v NEW,v
  1229.  
  1230. Advantages:
  1231.  
  1232.    * The log of changes is maintained intact.
  1233.  
  1234.    * The revision numbers are not affected.
  1235.  
  1236. Disadvantages:
  1237.  
  1238.    * Old releases of the module cannot easily be fetched from the
  1239.      repository.  (The file will show up as NEW even in revisions from
  1240.      the time before it was renamed).
  1241.  
  1242.    * There is no log information of when the file was renamed.
  1243.  
  1244.    * Nasty things might happen if someone accesses the history file
  1245.      while you are moving it.  Make sure no one else runs any of the CVS
  1246.      commands while you move it.
  1247.  
  1248. 
  1249. File: cvs.info,  Node: Rename by copying,  Prev: Inside,  Up: Moving files
  1250.  
  1251. Copying the history file
  1252. ========================
  1253.  
  1254.    This way also involves direct modifications to the repository.  It
  1255. is safe, but not without drawbacks.
  1256.  
  1257.      # Copy the RCS file inside the repository
  1258.      $ cd $CVSROOT/MODULE
  1259.      $ cp OLD,v NEW,v
  1260.      # Remove the old file
  1261.      $ cd ~/MODULE
  1262.      $ rm OLD
  1263.      $ cvs remove OLD
  1264.      $ cvs commit OLD
  1265.      # Remove all tags from NEW
  1266.      $ cvs update NEW
  1267.      $ cvs log NEW             # Remember the tag names
  1268.      $ cvs tag -d TAG1
  1269.      $ cvs tag -d TAG2
  1270.      ...
  1271.  
  1272.    By removing the tags you will be able to check out old revisions of
  1273. the module.
  1274.  
  1275. Advantages:
  1276.  
  1277.    * Checking out old revisions works correctly, as long as you use
  1278.      `-rTAG' and not `-DDATE' to retrieve the revisions.
  1279.  
  1280.    * The log of changes is maintained intact.
  1281.  
  1282.    * The revision numbers are not affected.
  1283.  
  1284. Disadvantages:
  1285.  
  1286.    * You cannot easily see the history of the file across the rename.
  1287.  
  1288.    * Unless you use the `-r rev' (*note commit options::.) flag when
  1289.      NEW is committed its revision numbers will start at 1.0 again.
  1290.  
  1291. 
  1292. File: cvs.info,  Node: Moving directories,  Next: History browsing,  Prev: Moving files,  Up: Top
  1293.  
  1294. Moving and renaming directories
  1295. *******************************
  1296.  
  1297.    If you want to be able to retrieve old versions of the module, you
  1298. must move each file in the directory with the CVS commands.  *Note
  1299. Outside::.  The old, empty directory will remain inside the repository,
  1300. but it will not appear in your workspace when you check out the module
  1301. in the future.
  1302.  
  1303.    If you really want to rename or delete a directory, you can do it
  1304. like this:
  1305.  
  1306.   1. Inform everyone who has a copy of the module that the directory
  1307.      will be renamed.  They should commit all their changes, and remove
  1308.      their working copies of the module, before you take the steps
  1309.      below.
  1310.  
  1311.   2. Rename the directory inside the repository.
  1312.  
  1313.           $ cd $CVSROOT/MODULE
  1314.           $ mv OLD-DIR NEW-DIR
  1315.  
  1316.   3. Fix the CVS administrative files, if necessary (for instance if
  1317.      you renamed an entire module).
  1318.  
  1319.   4. Tell everyone that they can check out the module and continue
  1320.      working.
  1321.  
  1322.  
  1323.    If someone had a working copy of the module the CVS commands will
  1324. cease to work for him, until he removes the directory that disappeared
  1325. inside the repository.
  1326.  
  1327.    It is almost always better to move the files in the directory
  1328. instead of moving the directory.  If you move the directory you are
  1329. unlikely to be able to retrieve old releases correctly, since they
  1330. probably depend on the name of the directories.
  1331.  
  1332. 
  1333. File: cvs.info,  Node: History browsing,  Next: Keyword substitution,  Prev: Moving directories,  Up: Top
  1334.  
  1335. History browsing
  1336. ****************
  1337.  
  1338.    Once you have used CVS to store a version control history--what
  1339. files have changed when, how, and by whom, there are a variety of
  1340. mechanisms for looking through the history.
  1341.  
  1342. * Menu:
  1343.  
  1344. * log messages::                Log messages
  1345. * history database::            The history database
  1346. * user-defined logging::        User-defined logging
  1347. * annotate::                    What revision modified each line of a file?
  1348.  
  1349. 
  1350. File: cvs.info,  Node: log messages,  Next: history database,  Up: History browsing
  1351.  
  1352. Log messages
  1353. ============
  1354.  
  1355.    Whenever you commit a file you specify a log message.
  1356.  
  1357.    To look through the log messages which have been specified for every
  1358. revision which has been committed, use the `cvs log' command (*note
  1359. log::.).
  1360.  
  1361. 
  1362. File: cvs.info,  Node: history database,  Next: user-defined logging,  Prev: log messages,  Up: History browsing
  1363.  
  1364. The history database
  1365. ====================
  1366.  
  1367.    You can use the history file (*note history file::.) to log various
  1368. CVS actions.  To retrieve the information from the history file, use
  1369. the `cvs history' command (*note history::.).
  1370.  
  1371.